ParcelLabel API
Get Status of Related Label(s)
Resource URL
UAT:
https://api.uat.nzpost.co.nz/parcellabel/v3/labels/{consignment_id}/relatedProduction:
https://api.nzpost.co.nz/parcellabel/v3/labels/{consignment_id}/relatedResource Description
Returns the status of all labels within a consignment and the other consignments in the same order.
Note - Order number is put in to the sender_reference_2 field in creating label request. When a consignment id with that order number is queried with the 'related' resource, all consignments with the same order number specified in sender_reference_2 field are returned.
Resource Information
| Attribute | Detail |
|---|---|
| Response Format | JSON |
| Requires Authentication | Yes |
| Rate Limited | 15 calls per second. If rate limit is exceeded, calls will be queued. Calls unprocessed for over 60 seconds will time out. |
Request Parameters
| Field Name | Description | Mand | Example |
|---|---|---|---|
| consignment_id | Unique id of a consignment | Yes | LLT2BL |
Sample Request
https://api.uat.nzpost.co.nz/parcellabel/v3/labels/LLT2BL/relatedResponse Parameters
The following lists the required fields in the /labels/{consignment_id}/related response message.
| Field Name | Description | Mand | Example |
|---|---|---|---|
| consignments | An array containing all consignments relating to the specific consignment within the same order. See Consignments Object Parameters. | Y | JSON Array |
| errors | An array containing error details. See Errors Object Parameters. | Y if request is unsuccessful | JSON Array |
| message_id | A unique id for the API call | Yes | e50895a0-72aa-11e5-9b3a-02578d875979 |
| success | Returns true if request is successful otherwise false | Yes | true |
Consignments Object Parameters
| Field Name | Description | Mand | Example |
|---|---|---|---|
| consignment_id | Unique identifier for all of the labels in the consignment. | Y | LLT2BL |
| consignment_status | Status of the consignment. See Consignment Status Values. | Y | Complete |
| consignment_url | Download URL for the consignment, in format PDF. | Y if the status of the consignment is Complete | https://api.nzpost.co.nz/parcellabel/v3/labels/LLT2BL?format=PDF |
| delivery_address | An object containing the delivery address details of the consignment. See Consignments - Delivery Address Object Parameters. | Y | JSON Object |
| labels | An array of the label objects within the consignment. See Consignments - Labels Object Parameters. | Y | JSON Array |
| page_urls | An array containing the download URLs for each page in the consignment, in format PNG. | Y if the status of the consignment is Complete | https://api.uat.nzpost.co.nz/parcellabel/v3/labels/LLT2BL?format=PNG&page=1 |
Consignments - Delivery Address Object Parameters
| Field Name | Description | Mand | Example |
|---|---|---|---|
| building_name | Building name of the delivery address. | N | Beta Company House |
| company_name | Name of company that the parcel is being delivered to. | Y if for domestic and is_collection = true | Beta Company |
| unit_type | Unit type (if applicable) of the delivery address. | N | Suite |
| unit_value | Unit value of the delivery address. | Y if domestic and unit_type is not blank | 5 |
| floor | Floor of the delivery address. | N | 3 |
| street_number | Street number of the delivery address. | N | 1600 |
| street | Street name of the delivery address. | Y if address_id, dpid and site_code are blank | Pennsylvania Avenue |
| suburb | Suburb of the delivery address. | Y if address_id, dpid and site_code are blank | Washington Central |
| city | City of the delivery address. | Y if address_id, dpid and site_code are blank | Washington |
| state | Regional, provincial or county name of the delivery address. | N | Delaware |
| locality_code | Country subdivision code identifier that the delivery address belongs to. | N | DE |
| country_code | Two character country code. For domestic labels, this must be set to NZ. | Y | US |
| postcode | Postal or zip code of the delivery address. | Y if address_id, dpid and site_code are blank | 89102 |
Consignments - Labels Object Parameters
| Field Name | Description | Mand | Example |
|---|---|---|---|
| label_id | Contains the unique label id which can be used to return individual label data | Yes | LLT2BL-1 |
| tracking_reference | The tracking reference for the label | Yes | 123456789856AC01 |
Consignment Status Values
| Status | Definition |
|---|---|
| Accepted | ParcelLabel Request has been received into NZ Post Group systems |
| Processing | ParcelLabel Request has passed all validation and has been passed to the Label Generator |
| Complete | Label Rendering has successfully created an image of all the labels |
| Complete with warnings | All label images have been generated successfully but the merchant logo was not able to be put into the label image |
| Failed | The Label Rendering has failed to create an image for at least one label |
Errors Object Parameters
| Field Name | Description | Example |
|---|---|---|
| code | Error code where first 3 digits are http status code, last three digits identify error type | 400002 |
| message | Description of error code | Invalid Parameter(s) |
| details | Description of specific error | Carrier is a mandatory field |
Sample Response
